/*******************************************************************************
 * Copyright 2011 Towee.net
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *******************************************************************************/
package net.towee.client.managers;

import java.util.List;

import net.towee.client.event.core.DocumentDeletedEvent;
import net.towee.client.event.core.DocumentRatedEvent;
import net.towee.client.event.core.DocumentReceivedEvent;
import net.towee.model.repo.DocumentData;
import net.towee.model.repo.DocumentType;

import com.google.gwt.user.client.rpc.AsyncCallback;

/**
 * Manager for operating with documents. Implementation should cache all
 * results.
 * 
 * <ul>The implementation MUST handler this PUSH events:
 * <li>New or updated document - {@link DocumentReceivedEvent}</li>
 * <li>Delete document - {@link DocumentDeletedEvent}</li>
 * <li>Document rated(TUPed) - {@link DocumentRatedEvent}</li>
 * </ul>
 * 
 * @author viiv.c58@gmail.com (Artem Artem'ev)
 */
public interface DocumentsManager {
	/**
	 * Find documents by name field. It also can filter documents by author,
	 * group or doc type. If any of this parameters is null, this method ignore
	 * it. If searching string empty or null it invoke
	 * {@link ServiceOperationErrorHandler.onOperationError}
	 * 
	 * @param str
	 * @param groupId
	 * @param authorId
	 * @param type
	 * @param offset
	 * @param limit
	 * @param handler
	 */
	public void findDocuments(String str, List<String> groupId, String authorId, List<DocumentType> type, int offset,
			int limit, AsyncCallback<List<DocumentData>> handler);

	/**
	 * Get recent documents by group and type. If any of this params will be
	 * null, it ignored.
	 * 
	 * @param offset
	 * @param perpage
	 * @param groupId
	 * @param types
	 * @param handler
	 */
	public void getDocuments(List<String> groupId, List<DocumentType> types, int offset,
			int limit, AsyncCallback<List<DocumentData>> handler);
	
	/**
	 * Return number of new documents for current loged in users
	 * @param list
	 * @param types
	 * @param handler
	 */
	void getRecentDocumentsCount(List<String> groupId, List<DocumentType> types,
			AsyncCallback<Integer> handler);

	/**
	 * Get async document by given docId
	 * 
	 * @param docId
	 * @param handler
	 */
	public void getDocument(String docId, AsyncCallback<DocumentData> handler);

	/**
	 * This method save given document in db. Given document must contain all
	 * identity data (name, group and author).
	 * 
	 * It also create document node for storing in tree(node field must be empty,
	 * it will be created on server side and returned with document)
	 * 
	 * On success it fire an event {@link DocumentReceivedEvent} and invoke
	 * success method in handler.
	 * 
	 * @param doc
	 * @param parentNodeId TODO
	 * @param handler
	 */
	public void saveDocument(DocumentData doc, String parentNodeId, AsyncCallback<DocumentData> handler);

	/**
	 * This method update given document and invoke handler method with changed
	 * document.
	 * 
	 * This document expect of updated data contain a DocumentDiff (if it wasn't
	 * in given document, it create new one with empty explain field) with patch
	 * id for undoing to previous revision of document.
	 * 
	 * On success it fire an event {@link DocumentReceivedEvent} and invoke
	 * success method in handler.
	 * 
	 * @param doc
	 * @param explain TODO
	 * @param handler
	 */
	public void changeDocument(DocumentData doc, String explain, AsyncCallback<DocumentData> handler);

	/**
	 * Thumbs Up document with given id. 
	 * On success fire an event {@link DocumentRatedEvent}
	 * 
	 * @param docId
	 */
	public void tupDocument(String docId, AsyncCallback<Boolean> handler);

	/**
	 * This method get async document revision with given number. It get path
	 * from server and apply it to current document.
	 * 
	 * It cache all revisions for fast getting it.
	 * 
	 * @param docId
	 * @param revNumber
	 * @param handler
	 */
	public void getDocumentRevision(String docId, int revNumber, AsyncCallback<DocumentData> handler);
}
